Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 3 - Text Encoding Converter Reference / Text Encoding Converter Functions

Creating and Deleting Converter objects /

TECCreateConverterFromPath

Creates a converter object that includes a specific conversion path--from a source encoding through intermediate encodings to a destination encoding--and returns a reference to it.

pascal OSStatus TECCreateConverterFromPath(
                     TECObjectRef *newEncodingConverter,
                     const TextEncoding inPath[],
                     ItemCount inEncodings);

newEncodingConverter

A pointer to a converter object reference. On return, the reference points to the newly created text converter object.

inPath[]

An ordered array of text encoding specifications, beginning with the source encoding specification and ending with the destination encoding specification.

inEncodings

The number of text encoding specifications in the inPath array.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) for a list of possible values. If this function returns a result code other than noErr, then it did not successfully create the converter object reference. If the current configuration of the converter does not support all of the encodings in the array, the function returns a kTextUnsupportedEncodingErr result code.

DISCUSSION

You use TECCreateConverterFromPath to create and obtain a reference to a converter object that specifies a conversion path you define. This function is faster than the function TECCreateConverter (page 91) since it does not need to search for a conversion path.

You specify the conversion sequence from the source encoding through intermediate encodings to the destination encoding. To do so, you create an array of text encoding specifications that identify the encoding conversions through which the text to be converted should pass.

In this array, each adjacent pair of text encodings you specify must represent a conversion that is supported by the current configuration of the Text Encoding Converter. Otherwise, the function returns an error result code and does not create the converter object. To determine each subsequent step in the sequence from the source to the destination encoding, use the function TECGetDestinationTextEncodings (page 74).

To remove a converter object, you must call the function TECDisposeConverter (page 93).